|
 |
 |
::
|
|
|
TMultiThread Delphi Component
TMultiThread is a Delphi component for use in Win32, Win64 (XP/Vista/7/8/10), OSX, iOS, Android and Linux software.
It's a non-visual class that helps creating a thread pool, for example for creating a multi threaded thumbnailer or any other task that needs many threads.
Use automatic mode or specify a max. thread count and simply add work to the class and the jobs are automatically distributed among the available threads, and when the work is ready a callback event is called with the result.
TMultiThread is optimized to be used for many threads of the same type but can be used for various work too.
It has a built-in message system to report progress etc., events for thread start, thread stop, option to automatically free the objects and no Synchronize() is used at all, so it is also safe to use the component in a .dll.
TMultiThread in shareware and commercial software?
The component comes with full source code and can be evaluated freely. If you like it and decide to use it in a freeware, shareware or commercial (or any other money making - advertising, in app. selling, etc.) product one of the licenses is needed.
Installation
Unpack the package (TMultiThread x.x.zip).
- Delphi 7:
- In Delphi menu: Component: Install component
- Unit file name: select "MultiThread2.pas"
- Compile and save package.
- Delphi 2009:
- Menu: File/New/Package Delphi
- In project manager (in the upper-right corner by default), right-click on "Package1.dproj" and select "Add..."
- Unit file name: click "Browse" and select "MultiThread2.pas" and click "Ok"
- Save the package giving it a proper name.
- In project manager (in the upper-right corner by default), right-click on "Package1.dproj" (if you saved the package with this name) and select "Install..."
- Save the package.
If everything went smooth, you can access the TMultiThread2 component on 3delite's tab.
Usage
Drop a TMultiThread component on the form. Create a class that will describe the job and the particular parameters for it. There is also a global Parameters class that you can assign your own class to it that is global parameters for all the jobs (threads).
Run the component with MultiThread1.Start, any work added from now on will start instantly if there is at least one work in (added) to the job list.
Use MultiThread1.AddWork(Work) to add a job to the TMultiThread component. When this function is called as soon as there is a thread ready it will be processed.
Implement a ThreadWorkerCallback event. When a job is ready to run, this event will be called. You get the global Parameters class and the job class here. Type-cast both to your class and you can extract the information describing the work to do. After the work is finished if you need to send back results, then define a Results class and assign it to Results. You will get back the Results class in the ThreadResultsCallback event. Be carefull not to use VCL stuff inside the ThreadWorkerCallback as the VCL is not thread-safe! If you want to for example send progress information from here, you can use the built in message function (see the tutorial program's ThreadWorkerCallback event).
Implement a ThreadResultsCallback event if you need some kind of results from the threads. When a thread finishes this event is called with your ready results. If you stoped the TMultiThread component before this event was called with Stop then this event will be called only for the already running threads.
When you are done or want to interrupt the threads call MultiThread1.Stop. Existing threads will finish their work (or abort if the work callback checks the Terminated property) and call the ThreadResultsCallback function.
To get the messages and results you need to periodically call CheckIncomingMessages and CheckIncomingResults. If there is at least one object arrived they will trigger the Message and ResultsCallbacks.
Note: It's also possible to first add the jobs and then start them processing when you call MultiThread1.Start.
Properties
- AutoFreeData: Automatically free the Job object after leaving ThreadResultsCallback() event or when a thread is terminated.
- AutoFreeResults: Automatically free the Results object after leaving ThreadResultsCallback() event or when a thread is terminated.
- AutoFreeMessages: Automatically free the Message objects after leaving ThreadMessage() event.
- AutoFreeParameters: Automatically free the Parameters objects when freeing the TMultiThread component.
- ThreadCount:
- tcAutomatic: Automatically fires at most "number of CPU cores count" threads.
- tcManual: Manually set the maximum number of threads to fire at a time. Use ThreadCountManual property to set the max. thread count.
- ThreadCountManual: Only used if tcManual is set. Specify maximum threads to run at the same time.
- ThreadPriority: The spawned threads priority. The spawned threads priority. Note that is only available under Windows.
- Active: True if .Start has been called and threads are running and ready to accept jobs, False otherwise.
Methodes
- Start: Run the threads and start accepting jobs.
- Stop: Stop all running threads. Clear the job (work) list if desired.
Inside the ThreadWorkerCallback check the thread's .Terminated property to get notified about a thread termination.
Also you have to free the Data class if you detect a terminate and AutoFreeData is False.
- StopAllThreads: Stop all running threads, clear the job (work) list, no new threads will be started.
Inside the ThreadWorkerCallback check the thread's .Terminated property to get notified about a thread termination.
Also you have to free the Data class if you detect a terminate and AutoFreeData is False.
Events
- ThreadMessage: If message is sent from the thread with the thread's SendMessage(MessageObject: TObject) function it arrives here.
- Sender: The TMultiThread class that calls this event.
- var MessageObject: The class that was sent as Message2.
Do not forget to free the classes before exiting this event if AutoFreeMessages is False!
- ThreadResultsCallback: When a thread finishes it's work this event is called.
- Sender: The TMultiThread class that calls this event.
- var Results: If Results was assigned to a class, you get the assigned Results class here.
Do not forget to free the classes before exiting this event if AutoFreeData and/or AutoFreeResults is False!
- ThreadWorkerCallback: This is the function that will be running inside a thread.
Be carefull what you do as for example VCL is not accessible here, so do not modify VCL controls inside here. All things that apply for threads in general applies here too.
- Thread: The thread class the function is called in.
- Parameters: If you specified a Parameters class for the TMultiThread component you get the Parameters class here.
- var Job: The Job that was given as the work. Use this class to identify the job, type-cast it to your own class implemented.
- var Results: Is nil by default, create a class and assign it to Results after the work has been done. You will get this class back in ThreadResultsCallback event.
- ThreadStartCallback: Called when a new thread starts. Usfull for initializing thread related stuff like CoInitialize.
- ThreadFinishedCallback: Called when a thread ends. Usfull for uninitializing thread related stuff like CoUnInitialize.
Useful information
|
|
|
|
|
|
